home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / EventSetDescriptor.java < prev    next >
Text File  |  1998-09-22  |  11KB  |  305 lines
  1. /*
  2.  * @(#)EventSetDescriptor.java    1.40 98/07/01
  3.  *
  4.  * Copyright 1996-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.beans;
  16.  
  17. import java.lang.reflect.*;
  18.  
  19. /**
  20.  * An EventSetDescriptor describes a group of events that a given Java
  21.  * bean fires.
  22.  * <P>
  23.  * The given group of events are all delivered as method calls on a single
  24.  * event listener interface, and an event listener object can be registered
  25.  * via a call on a registration method supplied by the event source.
  26.  */
  27.  
  28.  
  29. public class EventSetDescriptor extends FeatureDescriptor {
  30.  
  31.     /**
  32.      * This constructor creates an EventSetDescriptor assuming that you are
  33.      * following the most simple standard design pattern where a named
  34.      * event "fred" is (1) delivered as a call on the single method of
  35.      * interface FredListener, (2) has a single argument of type FredEvent,
  36.      * and (3) where the FredListener may be registered with a call on an
  37.      * addFredListener method of the source component and removed with a
  38.      * call on a removeFredListener method.
  39.      *
  40.      * @param sourceClass  The class firing the event.
  41.      * @param eventSetName  The programmatic name of the event.  E.g. "fred".
  42.      *        Note that this should normally start with a lower-case character.
  43.      * @param listenerType  The target interface that events
  44.      *        will get delivered to.
  45.      * @param listenerMethodName  The method that will get called when the event gets
  46.      *        delivered to its target listener interface.
  47.      * @exception IntrospectionException if an exception occurs during
  48.      *              introspection.
  49.      */
  50.     public EventSetDescriptor(Class sourceClass, String eventSetName,
  51.         Class listenerType, String listenerMethodName) 
  52.         throws IntrospectionException {
  53.  
  54.        setName(eventSetName);
  55.  
  56.     // Get a Class object for the listener class.
  57.         this.listenerType = listenerType;
  58.     
  59.     listenerMethods = new Method[1];
  60.     listenerMethods[0] = Introspector.findMethod(listenerType,
  61.                         listenerMethodName, 1);
  62.  
  63.     String listenerClassName = listenerType.getName();
  64.     String tail = listenerClassName.substring(listenerClassName.lastIndexOf('.') + 1);
  65.  
  66.     String addMethodName = "add" + tail;
  67.     addMethod = Introspector.findMethod(sourceClass, addMethodName, 1);
  68.  
  69.     String removeMethodName = "remove" + tail;
  70.     removeMethod = Introspector.findMethod(sourceClass, removeMethodName, 1);
  71.                     
  72.  
  73.     }
  74.  
  75.     /**
  76.      * This constructor creates an EventSetDescriptor from scratch using
  77.      * string names.
  78.      *
  79.      * @param sourceClass  The class firing the event.
  80.      * @param eventSetName The programmatic name of the event set.
  81.      *        Note that this should normally start with a lower-case character.
  82.      * @param listenerType  The Class of the target interface that events
  83.      *        will get delivered to.
  84.      * @param listenerMethodNames The names of the methods that will get called 
  85.      *        when the event gets delivered to its target listener interface.
  86.      * @param addListenerMethodName  The name of the method on the event source
  87.      *        that can be used to register an event listener object.
  88.      * @param removeListenerMethodName  The name of the method on the event source
  89.      *        that can be used to de-register an event listener object.
  90.      * @exception IntrospectionException if an exception occurs during
  91.      *              introspection.
  92.      */
  93.     public EventSetDescriptor(Class sourceClass,
  94.         String eventSetName, 
  95.         Class listenerType,
  96.         String listenerMethodNames[],
  97.         String addListenerMethodName,
  98.         String removeListenerMethodName)
  99.         throws IntrospectionException {
  100.     setName(eventSetName);
  101.     listenerMethods = new Method[listenerMethodNames.length];
  102.     for (int i = 0; i < listenerMethods.length; i++) {
  103.         listenerMethods[i] = Introspector.findMethod(listenerType,
  104.                     listenerMethodNames[i], 1);
  105.     }
  106.  
  107.     this.addMethod = Introspector.findMethod(sourceClass,
  108.                     addListenerMethodName, 1);
  109.     this.removeMethod = Introspector.findMethod(sourceClass,
  110.                     removeListenerMethodName, 1);
  111.  
  112.     this.listenerType = listenerType;
  113.     }
  114.  
  115.     /**
  116.      * This constructor creates an EventSetDescriptor from scratch using
  117.      * java.lang.reflect.Method and java.lang.Class objects.
  118.      *
  119.      * @param eventSetName The programmatic name of the event set.
  120.      * @param listenerType The Class for the listener interface.
  121.      * @param listenerMethods  An array of Method objects describing each
  122.      *        of the event handling methods in the target listener.
  123.      * @param addListenerMethod  The method on the event source
  124.      *        that can be used to register an event listener object.
  125.      * @param removeListenerMethod  The method on the event source
  126.      *        that can be used to de-register an event listener object.
  127.      * @exception IntrospectionException if an exception occurs during
  128.      *              introspection.
  129.      */
  130.     public EventSetDescriptor(String eventSetName, 
  131.         Class listenerType,
  132.         Method listenerMethods[],
  133.         Method addListenerMethod,
  134.         Method removeListenerMethod) 
  135.         throws IntrospectionException {
  136.     setName(eventSetName);
  137.     this.listenerMethods = listenerMethods;
  138.     this.addMethod = addListenerMethod;
  139.     this.removeMethod = removeListenerMethod;
  140.     this.listenerType = listenerType;
  141.     }
  142.  
  143.     /**
  144.      * This constructor creates an EventSetDescriptor from scratch using
  145.      * java.lang.reflect.MethodDescriptor and java.lang.Class objects.
  146.      *
  147.      * @param eventSetName The programmatic name of the event set.
  148.      * @param listenerType The Class for the listener interface.
  149.      * @param listenerMethodDescriptors  An array of MethodDescriptor objects
  150.      *         describing each of the event handling methods in the
  151.      *           target listener.
  152.      * @param addListenerMethod  The method on the event source
  153.      *        that can be used to register an event listener object.
  154.      * @param removeListenerMethod  The method on the event source
  155.      *        that can be used to de-register an event listener object.
  156.      * @exception IntrospectionException if an exception occurs during
  157.      *              introspection.
  158.      */
  159.     public EventSetDescriptor(String eventSetName, 
  160.         Class listenerType,
  161.         MethodDescriptor listenerMethodDescriptors[],
  162.         Method addListenerMethod,
  163.         Method removeListenerMethod) 
  164.         throws IntrospectionException {
  165.     setName(eventSetName);
  166.     this.listenerMethodDescriptors = listenerMethodDescriptors;
  167.     this.addMethod = addListenerMethod;
  168.     this.removeMethod = removeListenerMethod;
  169.     this.listenerType = listenerType;
  170.     }
  171.  
  172.     /** 
  173.      * @return The Class object for the target interface that will
  174.      * get invoked when the event is fired.
  175.      */
  176.     public Class getListenerType() {
  177.     return listenerType;
  178.     }
  179.  
  180.     /** 
  181.      * @return An array of Method objects for the target methods
  182.      * within the target listener interface that will get called when
  183.      * events are fired.
  184.      */
  185.     public Method[] getListenerMethods() {
  186.     if (listenerMethods == null && listenerMethodDescriptors != null) {
  187.         // Create Method array from MethodDescriptor array.
  188.         listenerMethods = new Method[listenerMethodDescriptors.length];
  189.         for (int i = 0; i < listenerMethods.length; i++) {
  190.         listenerMethods[i] = listenerMethodDescriptors[i].getMethod();
  191.         }
  192.     }
  193.     return listenerMethods;
  194.     }
  195.  
  196.  
  197.     /** 
  198.      * @return An array of MethodDescriptor objects for the target methods
  199.      * within the target listener interface that will get called when
  200.      * events are fired.
  201.      */
  202.     public MethodDescriptor[] getListenerMethodDescriptors() {
  203.     if (listenerMethodDescriptors == null && listenerMethods != null) {
  204.         // Create MethodDescriptor array from Method array.
  205.         listenerMethodDescriptors = 
  206.                 new MethodDescriptor[listenerMethods.length];
  207.         for (int i = 0; i < listenerMethods.length; i++) {
  208.         listenerMethodDescriptors[i] = 
  209.                 new MethodDescriptor(listenerMethods[i]);
  210.         }
  211.     }
  212.     return listenerMethodDescriptors;
  213.     }
  214.  
  215.     /** 
  216.      * @return The method used to register a listener at the event source.
  217.      */
  218.     public Method getAddListenerMethod() {
  219.     return addMethod;
  220.     }
  221.  
  222.     /** 
  223.      * @return The method used to register a listener at the event source.
  224.      */
  225.     public Method getRemoveListenerMethod() {
  226.     return removeMethod;
  227.     }
  228.  
  229.     /**
  230.      * Mark an event set as unicast (or not).
  231.      *
  232.      * @param unicast  True if the event set is unicast.
  233.      */
  234.  
  235.     public void setUnicast(boolean unicast) {
  236.     this.unicast = unicast;
  237.     }
  238.     
  239.     /**
  240.      * Normally event sources are multicast.  However there are some 
  241.      * exceptions that are strictly unicast.
  242.      *
  243.      * @return  True if the event set is unicast.  Defaults to "false".
  244.      */
  245.  
  246.     public boolean isUnicast() {
  247.     return unicast;
  248.     }
  249.  
  250.     /**
  251.      * Mark an event set as being in the "default" set (or not).
  252.      * By default this is true.
  253.      *
  254.      * @param unicast  True if the event set is unicast.
  255.      */
  256.  
  257.     public void setInDefaultEventSet(boolean inDefaultEventSet) {
  258.     this.inDefaultEventSet = inDefaultEventSet;
  259.     }
  260.     
  261.     /**
  262.      * Report if an event set is in the "default set".
  263.      *
  264.      * @return  True if the event set is in the "default set".  Defaults to "true".
  265.      */
  266.  
  267.     public boolean isInDefaultEventSet() {
  268.     return inDefaultEventSet;
  269.     }
  270.  
  271.     /*
  272.      * Package-private constructor
  273.      * Merge two event set descriptors.  Where they conflict, give the
  274.      * second argument (y) priority over the first argument (x).
  275.      * @param x  The first (lower priority) EventSetDescriptor
  276.      * @param y  The second (higher priority) EventSetDescriptor
  277.      */
  278.  
  279.     EventSetDescriptor(EventSetDescriptor x, EventSetDescriptor y) {
  280.     super(x,y);
  281.     listenerMethodDescriptors = x.listenerMethodDescriptors;
  282.     if (y.listenerMethodDescriptors != null) {
  283.         listenerMethodDescriptors = y.listenerMethodDescriptors;
  284.     }
  285.     if (listenerMethodDescriptors == null) {
  286.         listenerMethods = y.listenerMethods;
  287.     }
  288.     addMethod = y.addMethod;
  289.     removeMethod = y.removeMethod;
  290.     unicast = y.unicast;
  291.     listenerType = y.listenerType;
  292.     if (!x.inDefaultEventSet || !y.inDefaultEventSet) {
  293.         inDefaultEventSet = false;
  294.     }
  295.     }
  296.  
  297.     private Class listenerType;
  298.     private Method[] listenerMethods;
  299.     private MethodDescriptor[] listenerMethodDescriptors;
  300.     private Method addMethod;
  301.     private Method removeMethod;
  302.     private boolean unicast;
  303.     private boolean inDefaultEventSet = true;
  304. }
  305.